Skip to main content

wchar.h

Wide characters use two or four bytes to represent a single character, causing the regular C language character handling functions to fail. wchar.h defines a number of wide character-specific handling functions.

Type aliases and macros​

wchar.h defines a type alias, wint_t, for wide characters corresponding to integer values.

wchar.h also defines a macro WEOF, which indicates the wide character version of the end-of-file character EOF.

btowc(), wctob()​

btowc()` converts single-byte characters to wide characters, and wctob()` converts wide characters to single-byte characters.

wint_t btowc(int c);
int wctob(wint_t c);

`btowc() returns a wide character. If the argument is EOF, or if the conversion fails, WEOF is returned.

`wctob() returns a single-byte character. If the argument is WEOF, or if the argument wide character cannot correspond to a single single byte character, then EOF is returned.

The following is an example of usage.

wint_t wc = btowc('B'); 

// output the wide character B
wprintf(L "Wide character: %lc\n", wc);

unsigned char c = wctob(wc);

// output single-byte character B
wprintf(L "Single-byte character: %c\n", c);

fwide()​

fwide() is used to set whether a byte stream is a wide character stream, or a multi-byte character stream.

If a byte stream is processed using a wide character specific function, it will be set to be a wide character stream by default, otherwise it needs to be set explicitly using fwide().

int fwide(FILE* stream, int mode);

It accepts two arguments, the first being a file pointer and the second a byte stream mode, with three options.

  • 0: the byte stream mode is left as it is. -1 (or other negative value): set to a multi-byte character stream.
  • 1 (or other positive value): set to a wide character stream.

The return value of fwide() is also split into three cases: if it is a wide character stream, a positive value is returned; if it is a multi-byte character stream, a negative value is returned; if it is a normal character stream, 0 is returned.

Once the byte stream mode is set, it cannot be changed.

#include <stdio.h>
#include <wchar.h>

int main(void) {
  wprintf(L "Hello world!\n");
  int mode = fwide(stdout, 0);
  wprintf(L "Stream is %ls-orientated\n", mode < 0 ? L "byte" : L "wide");
}

In the above example, wprintf() implicitly sets the byte stream to wide character mode, so the return value of fwide(stdout, 0) is greater than zero.

Wide-character-specific functions​

The following functions are basically wide character versions of the character handling functions inside stdio.h, which must be used to manipulate wide characters.

  • fgetwc() fetches wide characters from a wide character stream, corresponding to fgetc().
  • fgetws() reads a wide string from a wide character stream, corresponding to fgets().
  • fputwc() Writes a wide character to a wide character stream, corresponding to fputc().
  • fputws() Writes a wide string to a wide stream, corresponding to fputs().
  • fwprintf() formats wide output to a wide stream, corresponds to fprintf().
  • fwscanf() Formatted wide input from a wide stream, corresponds to fscanf().
  • getwchar() Gets a wide character from stdin, corresponds to getchar().
  • getwc() Gets a wide character from stdin, corresponding to getc().
  • putwchar() Writes a wide character to stdout, corresponding to putchar().
  • putwc() writes a wide character to stdout, corresponding to putc().
  • swprintf() Format wide output to a wide string, corresponding to sprintf().
  • swscanf() Formatted wide input from a wide string, corresponds to sscanf().
  • ungetwc() Pushes wide characters back into the input stream, corresponds to ungetc().
  • vfwprintf() Formatted wide character output to a wide character stream with variable arguments, corresponds to vfprintf().
  • vfwscanf() Variable parameter formatted wide character input from a wide character stream, corresponds to vfscanf().
  • vswprintf() Variable parameter formatted wide character output to a wide string, corresponds to vswprintf().
  • vswscanf() Variable parameter formatted wide character input from a wide string, corresponds to vsscanf().
  • vwprintf() Variable parameter formatted wide character output, corresponds to vprintf().
  • vwscanf() Variable-parameter formatted wide character input, corresponding to vscanf().
  • wcscat() Dangerously concatenated wide strings, corresponds to strcat().
  • wcschr() Find wide characters in a wide string, corresponds to strchr().
  • wcscmp() compares wide strings, corresponds to strcmp().
  • wcscoll() compares two wide strings considering the language context, corresponds to strcoll().
  • wcscpy() dangerously copies a wide string, corresponds to strcpy().
  • wcscspn() does not count characters from the beginning of a wide string, corresponds to strcspn().
  • wcsftime() Formatted date and time output, corresponds to strftime().
  • wcslen() returns the length of a wide string, corresponds to strlen().
  • wcsncat() concatenates wide strings more securely, corresponds to strncat().
  • wcsncmp() compares wide strings of finite length, corresponds to strncmp().
  • wcsncpy() Safer copy of wide strings, corresponds to strncpy().
  • wcspbrk() Searches for one of a set of wide characters in a wide string, corresponds to strpbrk().
  • wcsrchr() Searches for a wide character in a wide string starting at the end, corresponds to strrchr().
  • wcsspn() counts characters from the set preceding a wide string, corresponding to strspn().
  • wcsstr() Finds a wide string within another wide string, corresponding to strstr().
  • wcstod() converts a wide string to a double, corresponding to strtod().
  • wcstof() converts a wide string to a float, corresponding to strtof().
  • wcstok() marks a wide string, corresponds to strtok().
  • wcstold() converts a wide string to a long double, corresponding to strtold().
  • wcstoll() converts a wide string to a long long, corresponding to strtoll().
  • wcstol() converts a wide string to long, corresponding to strtol().
  • wcstoull() converts a wide string to unsigned long long, corresponding to strtoull().
  • wcstoul() converts a wide string to unsigned long, corresponding to strtoul().
  • wcsxfrm() converts wide strings for comparison according to the language environment, corresponds to strxfrm().
  • wmemcmp() compares wide characters in memory, corresponds to memcmp().
  • wmemcpy() Copies wide characters in memory, corresponds to memcpy().
  • wmemmove() Copies wide character memory, possibly overlapping, corresponding to memmove().
  • wprintf() Format wide output, corresponds to printf().
  • wscanf() Format wide input, corresponds to scanf().

Multi-byte character-specific functions​

wchar.h also defines a number of functions specific to multibyte characters.

  • mbsinit() Determines whether mbstate_t is in the initial conversion state.
  • mbrlen() counts the number of bytes in a multibyte string given the conversion state, corresponding to mblen().
  • mbrtowc() Converts a multibyte character to a wide character given the conversion state, corresponds to mbtowc().
  • wctombr() Converts a wide character to a multibyte character given the conversion state, corresponds to wctomb().
  • mbsrtowcs() Converts multi-byte strings to wide strings given the conversion state, corresponds to mbstowcs().
  • wcsrtombs() Converts a wide string to a multibyte string given the conversion status, corresponds to wcstombs().